<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Skulpt API / Pytch environment &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Testing" href="testing.html" />
    <link rel="prev" title="Syscalls" href="syscalls.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="skulpt-api-pytch-environment">
<h1>Skulpt API / Pytch environment<a class="headerlink" href="#skulpt-api-pytch-environment" title="Link to this heading">¶</a></h1>
<p>We gather all runtime dependencies into one ‘environment’ object. This
allows automated testing outside the browser, via injection of mocks of
various things. It also keeps us honest in terms of being explicit about
what the external dependencies are.</p>
<p>The ‘environment’ object is the property <code class="docutils literal notranslate"><span class="pre">pytch</span></code> of the global
<code class="docutils literal notranslate"><span class="pre">Sk</span></code> object.</p>
<section id="error-handling">
<h2>Error handling<a class="headerlink" href="#error-handling" title="Link to this heading">¶</a></h2>
<p>If a Pytch thread raises a Python-level exception, this is caught
inside <code class="docutils literal notranslate"><span class="pre">Thread.one_frame()</span></code> and passed to the following
function-valued property of the <code class="docutils literal notranslate"><span class="pre">Sk.pytch</span></code> configuration object:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">on_exception</span></code> — function which is passed the JavaScript-level
error (often it is also a Python exception object) and an ‘error
context’ describing how the error occurred.</p></li>
</ul>
<p>In tests, any errors are collected into a list. Some tests are expected
to cause errors, and this can be verified by examining that list. Most
tests should not cause any errors; an end-of-test hook verifies that no
errors remain unprocessed.</p>
<p>In the web-app, exceptions are displayed in a dedicated pane.</p>
</section>
<section id="loading-costumes-backdrops">
<h2>Loading costumes / backdrops<a class="headerlink" href="#loading-costumes-backdrops" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">async_load_image</span></code></p></li>
</ul>
<p>Used in async registration of actor (sprite, stage) classes.</p>
</section>
<section id="loading-playing-stopping-monitoring-sounds">
<h2>Loading, playing, stopping, monitoring sounds<a class="headerlink" href="#loading-playing-stopping-monitoring-sounds" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">sound_manager</span></code></p></li>
</ul>
<p>See <a class="reference internal" href="sounds.html"><span class="doc">separate section</span></a>.</p>
</section>
<section id="keyboard">
<h2>Keyboard<a class="headerlink" href="#keyboard" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">keyboard</span></code></p></li>
</ul>
<p>Require an object to keep track of keys’ states. Need to be able to ask
whether a key is currently up or down, and to know which keys have gone
from up to down since we last asked. Maintain a list of ‘key down’
events inside the ‘keyboard’ object, and provide a way for caller to
take ownership of (‘drain’) the events in that queue.</p>
<p>Have methods:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">key_pressed(k)</span></code> — predicate asking whether given key is
currently in the ‘down’ position</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">drain_new_keydown_events()</span></code> — obtain list of new up-&gt;down
transitions and empty the in-keyboard storage of that queue</p></li>
</ul>
<p>A real keyboard will maintain internal state based on browser events.
Mock keyboard for testing which has methods to simulate key events.</p>
<p>Hat-block for ‘when pressed’; keypress handlers stored in <code class="docutils literal notranslate"><span class="pre">PytchActor</span></code>
instance (next to green-flag and message, since these are all-instance
events); there is a predicate syscall <code class="docutils literal notranslate"><span class="pre">pytch.is_key_pressed()</span></code>.</p>
</section>
<section id="mouse">
<span id="skulpt-pytch-environment-mouse"></span><h2>Mouse<a class="headerlink" href="#mouse" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">mouse</span></code></p></li>
</ul>
<p>Similar to keyboard; have list of ‘click events’ which can be drained.
Also similar: mock and real. Real (web-app) has to do some coord
transformations. (DOC TODO: Describe real mouse here or under web-app?)</p>
</section>
<section id="current-live-project">
<h2>Current live project<a class="headerlink" href="#current-live-project" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">current_live_project</span></code></p></li>
</ul>
<p>So the web-app knows which <code class="docutils literal notranslate"><span class="pre">Project</span></code> to interact with. Where to send
green-flag events, which project to ask for list of rendering
instructions.</p>
</section>
<section id="currently-executing-thread">
<h2>Currently executing thread<a class="headerlink" href="#currently-executing-thread" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">executing_thread</span></code></p></li>
</ul>
<p>Some functions only make sense within the context of a Pytch thread.
Other functions need to know which thread they’re running in, to look
up thread-local state such as whether loops should yield every
iteration.  Since only one thread runs at a time, we can store the
currently executing thread in <code class="docutils literal notranslate"><span class="pre">Sk.pytch.executing_thread</span></code>.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">VM</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="integration-with-client.html">Integration with client</a></li>
<li class="toctree-l3"><a class="reference internal" href="based-on-skulpt.html">Skulpt: Python / JavaScript bridge</a></li>
<li class="toctree-l3"><a class="reference internal" href="project.html">Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor.html">Actor: Sprite and Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor-registration.html">Actor-class registration</a></li>
<li class="toctree-l3"><a class="reference internal" href="threading-model.html">Threading model</a></li>
<li class="toctree-l3"><a class="reference internal" href="hat-blocks.html">Hat blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="syscalls.html">Syscalls</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Skulpt API / Pytch environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="ide-web-app.html">Web-app</a></li>
<li class="toctree-l3"><a class="reference internal" href="rendering.html">Rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="hit-detection.html">Collision and click detection</a></li>
<li class="toctree-l3"><a class="reference internal" href="clones.html">Clones</a></li>
<li class="toctree-l3"><a class="reference internal" href="sounds.html">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l3"><a class="reference internal" href="docstrings.html">Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="attribute-watchers.html">Watching object attributes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>